home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2001 May / SGI IRIX Base Documentation 2001 May.iso / usr / share / catman / p_man / cat2 / standard / recv.z / recv
Encoding:
Text File  |  1998-10-20  |  7.3 KB  |  198 lines
  1.  
  2.  
  3.  
  4. RRRREEEECCCCVVVV((((2222))))                                                                RRRREEEECCCCVVVV((((2222))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      recv, recvfrom, recvmsg - receive a message from a socket
  10.  
  11. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  12.      ####iiiinnnncccclllluuuuddddeeee <<<<ssssyyyyssss////ttttyyyyppppeeeessss....hhhh>>>>
  13.      ####iiiinnnncccclllluuuuddddeeee <<<<ssssyyyyssss////ssssoooocccckkkkeeeetttt....hhhh>>>>
  14.  
  15.      iiiinnnntttt rrrreeeeccccvvvv((((iiiinnnntttt ssss,,,, vvvvooooiiiidddd ****bbbbuuuuffff,,,, iiiinnnntttt lllleeeennnn,,,, iiiinnnntttt ffffllllaaaaggggssss))));;;;
  16.      iiiinnnntttt rrrreeeeccccvvvvffffrrrroooommmm((((iiiinnnntttt ssss,,,, vvvvooooiiiidddd ****bbbbuuuuffff,,,, iiiinnnntttt lllleeeennnn,,,, iiiinnnntttt ffffllllaaaaggggssss,,,,
  17.                ssssttttrrrruuuucccctttt ssssoooocccckkkkaaaaddddddddrrrr ****ffffrrrroooommmm,,,, iiiinnnntttt ****ffffrrrroooommmmlllleeeennnn))));;;;
  18.      iiiinnnntttt rrrreeeeccccvvvvmmmmssssgggg((((iiiinnnntttt ssss,,,, ssssttttrrrruuuucccctttt mmmmssssgggghhhhddddrrrr ****mmmmssssgggg,,,, iiiinnnntttt ffffllllaaaaggggssss))));;;;
  19.  
  20. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  21.      _R_e_c_v, _r_e_c_v_f_r_o_m, and _r_e_c_v_m_s_g are used to receive messages from a socket.
  22.  
  23.      The _r_e_c_v call is normally used only on a _c_o_n_n_e_c_t_e_d socket (see
  24.      _c_o_n_n_e_c_t(2)), while _r_e_c_v_f_r_o_m and _r_e_c_v_m_s_g may be used to receive data on a
  25.      socket whether it is in a connected state or not.
  26.  
  27.      If _f_r_o_m is non-zero, the source address of the message is filled in.
  28.      _F_r_o_m_l_e_n is a value-result parameter, initialized to the size of the
  29.      buffer associated with _f_r_o_m, and modified on return to indicate the
  30.      actual size of the address stored there.  A successful call returns the
  31.      length of the message.  If a message is too long to fit in the supplied
  32.      buffer, excess bytes may be discarded depending on the type of socket the
  33.      message is received from (see _s_o_c_k_e_t(2)).
  34.  
  35.      If no messages are available at the socket, the receive call waits for a
  36.      message to arrive, unless the socket is nonblocking (see _i_o_c_t_l(2)) in
  37.      which case the call returns -1 with the external variable errno set to
  38.      EWOULDBLOCK.
  39.  
  40.      The _s_e_l_e_c_t(2) call may be used to determine when more data arrives.
  41.  
  42.      The _f_l_a_g_s argument to a recv call is formed by _o_r'ing one or more of the
  43.      values,
  44.  
  45.        #define MSG_OOB      0x1  /* process out-of-band data */
  46.        #define MSG_PEEK     0x2  /* peek at incoming message */
  47.        #define MSG_WAITALL  0x40 /* wait for full request or error */
  48.        #define MSG_DONTWAIT 0x80 /* this message should be nonblocking */
  49.  
  50.      The _r_e_c_v_m_s_g call uses a _m_s_g_h_d_r structure to minimize the number of
  51.      directly supplied parameters.  This structure has the following form, as
  52.      defined in <_s_y_s/_s_o_c_k_e_t._h>:
  53.  
  54.           struct msghdr {
  55.                caddr_t   msg_name; /* optional address */
  56.                int  msg_namelen;   /* size of address */
  57.                struct    iovec *msg_iov;     /* scatter/gather array */
  58.                int  msg_iovlen;    /* # elements in msg_iov */
  59.  
  60.  
  61.  
  62.                                                                         PPPPaaaaggggeeee 1111
  63.  
  64.  
  65.  
  66.  
  67.  
  68.  
  69. RRRREEEECCCCVVVV((((2222))))                                                                RRRREEEECCCCVVVV((((2222))))
  70.  
  71.  
  72.  
  73.               caddr_t    msg_accrights; /* access rights sent/received */
  74.                int  msg_accrightslen;
  75.           };
  76.  
  77.      Here _m_s_g__n_a_m_e and _m_s_g__n_a_m_e_l_e_n specify the destination address if the
  78.      socket is unconnected; _m_s_g__n_a_m_e may be given as a null pointer if no
  79.      names are desired or required.  The _m_s_g__i_o_v and _m_s_g__i_o_v_l_e_n describe the
  80.      scatter/gather locations.  The _i_o_v_e_c structure is defined as
  81.  
  82.           struct iovec {
  83.                caddr_t   iov_base;
  84.                int  iov_len;
  85.           };
  86.  
  87.      Each _i_o_v_e_c entry specifies the base address and length of an area in
  88.      memory where data should be placed. _r_e_c_v_m_s_g will always fill an area
  89.      completely before proceeding to the next.
  90.  
  91.      A buffer to receive any access rights sent along with the message is
  92.      specified in _m_s_g__a_c_c_r_i_g_h_t_s, which has length _m_s_g__a_c_c_r_i_g_h_t_s_l_e_n.  Access
  93.      rights are opaque data that are interpreted within the context of the
  94.      communication domain and are currently limited to file descriptors, which
  95.      each occupy the size of an iiiinnnntttt (see _u_n_i_x(7F) for details).
  96.  
  97. RRRREEEETTTTUUUURRRRNNNN VVVVAAAALLLLUUUUEEEE
  98.      These calls return the number of bytes received, or -1 if an error
  99.      occurred.
  100.  
  101. EEEERRRRRRRROOOORRRRSSSS
  102.      The calls fail if:
  103.  
  104.      [EBADF]             The argument _s is an invalid descriptor.
  105.  
  106.      [ENOTSOCK]          The argument _s is not a socket.
  107.  
  108.      [EWOULDBLOCK]       The socket is marked non-blocking and the receive
  109.                          operation would block.
  110.  
  111.      [EINTR]             The receive was interrupted by delivery of a signal
  112.                          before any data was available for the receive.
  113.  
  114.      [EFAULT]            The data was specified to be received into a non-
  115.                          existent or protected part of the process address
  116.                          space.
  117.  
  118. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  119.      fcntl(2), getsockopt(2), read(2), select(2), send(2), socket(2)
  120.  
  121. NNNNOOOOTTTTEEEESSSS
  122.      ABI-compliant versions of the above calls can be obtained from
  123.      _l_i_b_s_o_c_k_e_t._s_o.
  124.  
  125.  
  126.  
  127.  
  128.                                                                         PPPPaaaaggggeeee 2222
  129.  
  130.  
  131.  
  132.  
  133.  
  134.  
  135. RRRREEEECCCCVVVV((((2222))))                                                                RRRREEEECCCCVVVV((((2222))))
  136.  
  137.  
  138.  
  139.      When using _r_e_c_v_m_s_g to receive access rights, it may be necessary for the
  140.      application to request a single byte of normal data as well, so that the
  141.      call does not return immediately if the access rights are not yet
  142.      present.  Doing so will cause the _r_e_c_v_m_s_g call to block until the access
  143.      rights are available.
  144.  
  145.  
  146.  
  147.  
  148.  
  149.  
  150.  
  151.  
  152.  
  153.  
  154.  
  155.  
  156.  
  157.  
  158.  
  159.  
  160.  
  161.  
  162.  
  163.  
  164.  
  165.  
  166.  
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.                                                                         PPPPaaaaggggeeee 3333
  195.  
  196.  
  197.  
  198.